Skip to main content

2.1 Prerequisites

Domain Name​

Before you even host Blink, you'll need a domain of your choosing (for example, https://bit.ly) and think about how you want Blink to shorten your links.

In the .env file, you'll notice that there are HOMEPAGE and BASE_URL variables you can configure. The HOMEPAGE is the page you are redirected to when you visit the "base" path (e.g. https://bit.ly -> https://bitly.com), and the BASE_URL forms the "base" path of any link you shorten (e.g. with BASE_URL of https://bit.ly, your shortened links will be https://bit.ly/abcd).

In fact, it's not even required to host Blink with the root domain (e.g. https://bit.ly) but instead use a subdomain as the BASE_URL (e.g. https://links.bitly.com).

Link Structure & Link Shortening Behaviour

So far we have always specified the protocol (https://) in our links. Technically, you can omit the protocol and just set HOMEPAGE/BASE_URL to, say, bit.ly/bitly.com, but it is recommended that you:

  1. Always include https:// (and NOT http://)
  2. Strip out the www.

The links, once shortened, exhibit similar behaviour: by default, we always force https:// and strip out the www, so if you shorten http://www.nodejs.org or just www.nodejs.org, the shortened link will always redirect to https://nodejs.org instead.

Identity Provider​

One thing you'll need no matter which approach you take to install Blink is an external identity provider (SSO) that speaks OIDC protocol. In short, it is a central place to register and manage users, and Blink will use the information provided by the SSO to provision users locally, without needing to get the user's credentials/passwords.

In general, any SSO nowadays support the OIDC protocol, which means Blink can work with it. SSOs with OIDC support include:

  • Keycloak (which is what we use for development as well)
  • Azure Active Directory
  • Google Workspace Identity
  • Okta
  • Auth0

etc.

Note that if you only have LDAP directories, you can use Keycloak or similar "gateway" software (such as dex or any of the "commercial" SSO products) to expose your user directory via OIDC.

OIDC Configuration​

Once you have your identity provider, you will need to configure the Blink server to talk to your SSO and the SSO to talk to the Blink server. I will use Keycloak's documentation for example below, but note that I am only using features that are part of the standard OIDC protocol, so the same process applies for all OIDC SSOs, whether you're using AD or Okta.

Client​

First, you must create an OIDC client for Blink so that Blink can talk to the OIDC/SSO server. See https://www.keycloak.org/docs/latest/server_admin/#oidc-clients for an example of how to do so (similar principles/steps should apply for other SSO providers).

You'll need to find/set a client id (it may be autogenerated by your identity provider; if not, simply set it as blink-app). Additionally, you should allow CORS/redirect to your BASE_URL/*, so that once users have signed in with your SSO, it can redirect users back to Blink.

Once you're done, set the OIDC_CLIENT_ID environment variable to the client ID of the OIDC client you just created, and set OIDC_ISSUER_BASE_URL to the OIDC issuer's base url or its .well-known endpoint if you happen to know it (the latter is recommended).

info

To learn more about how to set environment variables, please visit the Configuration page.

tip

If you identity provider is reachable by both the public and private/internal network, use the internal address, as the provider will give out the public addresses via its .well-known endpoint regardless. This is useful in cases where you are self-hosting your identity provider as well and communicates via the internal network (e.g. docker/docker-compose network).

OIDC Protocol​

While the default settings should work in most cases, to be safe, you should configure the OIDC protocol of your client/realm/domain to work with Blink.

First, enable the Standard Flow protocol for accessing OIDC (it should be enabled by default in most cases). Blink does not use Implicit Flow or need Direct Access Grants to authenticate with your SSO.

Second, the provider should allow token_endpoint_auth_method of none (again, in most cases, it should by default). This allows Blink to authenticate with your identity provider without passing out the OIDC client secret. You can check with your identity provider's OIDC .well-known endpoint to see if none is a supported method.

note

The reason we are able to use the token endpoint without authenticating with the client secret is that we use an asymmetric signing algorithm (such as RS256) to verify whatever tokens we get back without the need for a client secret!

And as the asymmetric signing algorithm may suggest, this means that Blink is indeed a public application (which means a very specific thing in the OAuth2 spec), not expected to hold any secrets. Therefore, you should ensure that the OIDC provider does support public applications like this.

However, in some rare cases, the OIDC provider may still require a client secret even though it supports asymmetric signing algorithms (e.g. Google Workspace). In that case, you can specify an alternate client authentication method (because remember, none means no secret is ever sent out) by specifying OIDC_TOKEN_ENDPOINT_AUTH_METHOD to something else (again, please check your provider's well-known endpoint to see which methods are supported), and specify the OIDC_CLIENT_SECRET environment variable.